home *** CD-ROM | disk | FTP | other *** search
/ Meeting Pearls 2 / Meeting Pearls Vol. II (1995)(GTI - Schatztruhe)[!].iso / Pearls / comm / XemRip / xemrip.doc < prev    next >
Text File  |  1994-11-20  |  16KB  |  438 lines
  1.     xemrip.library documentation
  2.  
  3. `xemrip.library' V1.2 -    Copyright © 1994 Stef Rave    20-Nov-94
  4.  
  5. xemrip.library is freeware (You may copy and use it for free)
  6.  
  7.  
  8.  
  9. No guarantee of any kind is given that the program described in this document
  10. is 100% reliable. You are using this material on your own risk.
  11.  
  12.  
  13.    Introduction           
  14.    Installation           
  15.    The preferences window 
  16.    Text variables         
  17.    Problems               
  18.    To-do                  
  19.    History                
  20.    Bug reports            
  21.    Copyright & legal stuff
  22.  
  23.  
  24.  
  25.  
  26.         Introduction
  27.  
  28. The xemrip.library is an external library for XEM V2.0
  29. compatible terminal programs like 'TERM'. It uses the RIP (Remote Imaging
  30. Protocol Script language) for the transmission of graphics and gadgets. The
  31. xemrip.library will run form kickstart V2.04 (v37) and up. The xemrip.library
  32. supports almost all commands of the RIP V 1.54 protocol. 
  33.  
  34. I saw rip with RIPcomm v0.15 I wanted to use it, but it didn't work
  35. very fine, some commands where missing and I wanted to use it with other
  36. terminal programs like 'TERM'. So I decided to write an external library. The
  37. first version was programmed in a period of 19 day.
  38.  
  39.  
  40. The library will keep all icons in memory so it is doesn't need to
  41. convert the icons every time they are loaded. The screens will be updated
  42. faster but you will need enough memory to load all icons the host terminal will
  43. instruct the xemrip.library to be displayed. From kick 3.0 a low memory handler
  44. will be added so that the icons will be unloaded if you don't have enough
  45. memory.
  46.  
  47. Form version 1.2 the library now can use user variables
  48.  
  49.  
  50.  
  51.  
  52.         Installation
  53.  
  54. The easiest way to instal the xemrip.library is to run the installation script
  55. for the 'installer' program. If you don't have the installer program you must
  56. install it by hand. 
  57.  
  58.      Installing by hand          
  59.      Configuring terminal program
  60.  
  61.  
  62.  
  63.  
  64.         Installing by hand
  65.  
  66. (The example commands must be executed form the directory where this doc is
  67. in)
  68.  
  69.  
  70. Copy to libs/xemrip.library form to the libs: directory.
  71.         'copy libs/xemrip.library libs:'
  72.  
  73. Copy the bitmap fonts to the fonts: directory
  74.         'copy fonts/#? fonts: all'
  75.  
  76.  
  77. Make a directory where scalable fonts subdirectory, icons subdirectory  and
  78. demofiles are stored
  79.         'makedir <destenationdirectory>'
  80.  
  81. Copy icons fonts and demofiles
  82.         'copy 'rip/#? <destenationdirectory> all
  83.  
  84. Add an assign command to the userstartup file
  85.         'echo >>S:User-Startup "Assign rip: <destenationdirectory>"'
  86.  
  87. Assign rip if you want to use ripterm right now
  88.         'Assign rip: <destenationdirectory>'
  89.  
  90.  
  91.  
  92.  
  93.         Configuring terminal program
  94.  
  95. After you have installed the xemrip.library, you must configure the terminal
  96. program. You must make the terminal program use the xemrip.library and change
  97. the screen size and depth.
  98.  
  99. To must fist the terminal program use the xemrip.library. How to do this
  100. depends on the terminal program, so you better read the manual of the terminal
  101. program.
  102.  
  103. If you use 'TERM':
  104.         Select  'terminal' in the 'settings' pull down menu.
  105.         Switch the 'Emulation' gadget until it says 'External'.
  106.         Enter 'xemrip.library' in the 'Emulation Name' gadget.
  107.  
  108.  
  109. When you have done this you should change the screen. The screen size for the
  110. rip protocol is 640*350 and 16 colors. You can check if the window is big
  111. enough by opening the status window in TERM: Select 'Status' in the 'Windows'
  112. pulldown menu. The Screen size in displayed in that window must be at least
  113. 80*43 (text size). If you don't own a VGA or multiscan monitor you will need an
  114. interlaced screenmode. It doesn't matter if the screen is to big, but if the
  115. screen is to small the lower or right part is clipped away and if buttons are
  116. placed there you can't select or see them.  It is also important that you use a
  117. 16 color screen, because if you don't the systems flood fill command will be
  118. used which is a lot slower than my own one, and the colors won't look
  119. correctly.
  120.  
  121.  
  122. You also may want to change the screen colors. In version 1.2 the library can
  123. change the palette its self. The default rip colors are:
  124.      ColorNr   Color                   values (r g b)  (range 0 - 15)
  125.      -------------------------------------------------------
  126.      1        Black                      0   0   0
  127.      2        Blue                       0   0  11
  128.      3        Green                      0  11   0
  129.      4        Cyan                       0  11  11
  130.      5        Red                       11   0   0
  131.      6        Magenta                   11   0  11
  132.      7        Brown                     11  11   0
  133.      8        Light Gray                11  11  11
  134.      9        Dark Gray                  6   6   6
  135.      10       Light Blue                 3   3  15
  136.      11       Light Green                3  15   3
  137.      12       Light Cyan                 3  15  15
  138.      13       Light Red                 15   3   3
  139.      14       Light Magenta             15   3  15
  140.      15       Yellow                    15  15   3
  141.      16       White                     15  15  15
  142.  
  143.  
  144. If all is OK a text has appeared on the screen. If is hasn't a menu options
  145. like 'reset terminal' should be somewhere in the pull down menus.
  146.  
  147.  
  148.  
  149.  
  150.  
  151.         User variables
  152.  
  153. Form version 1.2 the library now can use text variables
  154.  
  155. A special feature of the RIP protocol allows it to understand what a text
  156. variable is. A text variable is a piece of text that the riplibrary knows
  157. something more about.  For example, the text variable 'DATE' is known to
  158. represent the current Date on your computer.  The BBS may ask your computer
  159. what the values of one or more of these variables is, and if the riplibrary
  160. knows that particular text variable, it will tell the BBS.
  161.  
  162.  There are two types of Text Variables.  There are built-in text variables that
  163. riplibrary will always know about. Then there are also user text variables that
  164. can contain a variety of information depending on what the user of riplibrary
  165. entered at the time the variable was created.  For example, the BBS might ask
  166. you what the contents of the 'FULL_NAME' variable is, and if riplibrary doesn't
  167. know, it will pop-up a requester on the screen and ask you about it. Where you
  168. can enter the data.
  169.  
  170.  If you don't want to enter the data you can press Cancel and nothing will be
  171. send. If you press Send the data will be send to the BBS and the riplibrary
  172. will forget the data. If you press Add to Database the data will be send to the
  173. BBS and it will be stored in a database. From then on, riplibrary will remember
  174. that piece of information for the next time it is needed by a BBS. The BBS can
  175. also define text variables, the BBS can tell the riplibrary to store the
  176. variable in the database or temporarily in memory. If you edit a temporarily
  177. variable in the variable editor it will be added to the  database.
  178.  
  179.  
  180. Some examples of user text variables
  181.  
  182.     Variable        Information Stored in variable
  183.     --------------  ------------------------------
  184.     FIRST_NAME      Jimmy
  185.     LAST_NAME       McLemming
  186.     PHONE_NUMBER    13-11111
  187.  
  188.  
  189.  
  190.         The preferences window
  191.  
  192. To get to the preferences window you must select the emulations options menu.
  193. How to do this depends on the terminal program, so you better read the manual
  194. of the terminal program.
  195.  
  196. If you use 'TERM':
  197.         Select  'Emulation' in the 'settings' pull down menu.
  198.  
  199. You should now get these options 
  200.  
  201.  
  202.      Replay RIP Files       Play back rip sequences
  203.      VariableEditor         Get the variableeditor
  204.      Use RIP-Palette        Enable the xemrip library to change  the palette
  205.      Pause Timeout          Enter the time the library  waits before clearing
  206.      Main Rip directory     Enter the main rip directory 
  207.      Ripicons directory     Enter the name where the ripicons  are stored
  208.      Ripfonts directory     Enter the name where the vector  fonts are stored
  209.  
  210.  
  211.  
  212.  
  213.         Replay RIP File
  214.  
  215. If you have selected this option, asl requester will pop up and you can select
  216. a file.
  217.  
  218. If you replay captures then what you see can differ from the time that you
  219. recorded the capture. This happened because some buttons can contain
  220. ripcommands like 'reset screen'. If you pressed such a button the screen will
  221. be cleared but this is not recorded in the capture.
  222.  
  223. If you record a capture that you want to replay later, you must make sure that
  224. the capture filter is turned off. (If the terminal uses the capture filter)
  225.  
  226.  
  227.  
  228.  
  229.  
  230.         User Variable Editor
  231.  
  232. Here you can edit Th. user text variables.
  233.  
  234.  
  235. Variable    : The text variable must be entered here. You can only enter
  236.               letters and the undersquare '_'
  237.  
  238. ReturnText  : This will be send back if the BBS queries for the variable.
  239.               Some variables force you to fill in something if it is 
  240.               defines be the BBS.
  241.  
  242. New         : Create a new variable
  243.  
  244. Delete      : Delete this variable
  245.  
  246.  
  247.  
  248.  
  249.         Use RIP-Palette
  250.  
  251. If this option is selected the library can change the colors of the terminals
  252. screen. I have made this option because if the terminal uses a public screen
  253. like the workbench the other window will also use those colors. Also the
  254. terminal program doesn't know about the color changes so if it will open a
  255. window the colors may be wrong.
  256.  
  257.  
  258.  
  259.  
  260.  
  261.         Pause Timeout
  262.  
  263. There is also another option in the Emulation window 'Pause Timeout'. With this
  264. gadget you can set the time the library must wait before rebuilding the screen
  265. if a '|#' command has occurred. In version 1.2 I have changed this a bit,
  266. because the library sometimes waited when it wasn't necessary so the emulation
  267. could seem a bit slow.
  268.  
  269. There will only be waited after a rip_no_more '|#' command
  270.     -when the screen must be cleared
  271.     -there is no text displayed after the rip_no_more command
  272.      (except for button text)
  273.     -The left mouse button isn't pressed after the rip_no_more command
  274.  
  275.  
  276.  
  277.  
  278.  
  279.         Main Rip directory
  280.  
  281. In this text gadget you must enter the main rip directory. The library will
  282. look in this directory if it must replay a rip sequence.
  283.  
  284. The default is: "RIP:"
  285.  
  286.  
  287.  
  288.  
  289.  
  290.         Ripicons directory
  291.  
  292. In this text gadget you must enter directory name where the ripicons are
  293. stored.
  294.  
  295. The default is: "RIP:Icons"
  296.  
  297.  
  298.  
  299.  
  300.         Ripfonts directory
  301.  
  302. In this text gadget you must enter directory name where the vector fonts are
  303. stored.
  304.  
  305. The default is: "RIP:Fonts"
  306.  
  307.  
  308.  
  309.  
  310.         Problems
  311.  
  312.  -I get just ANSI commands....
  313.     The library can not always react quick enough to 'tell' the
  314.     BBS it can use RIP commands. On almost all BBSsss you can
  315.     select RIP after you logged in. If you can't find the menu
  316.     in the BBS to use RIP commands you should ask the sysop
  317.  
  318.  -My computer crashes when I log in after I configured the xemrip.library
  319.   in the phonebook.
  320.     This is because of a bug in TERM 4.0. You must select the configuration
  321.     before you logged in. You can do this by selecting the BBS-name any press
  322.     'USE-Entry' gadget.
  323.  
  324.  
  325.  
  326.  
  327.         To do
  328.  
  329.  -Add missing ripcommands: (didn't see a BBS that used them yet)
  330.          RIP_BEGIN_TEXT
  331.          RIP_REGION_TEXT
  332.          RIP_END_TEXT
  333.  -Make my fill routine work with other depths than 4-bitplanes
  334.  -Pop up command
  335.  -Add an options in the emulator menu like maximum icons stored in memory
  336.  -Use shared pens on public screens (kick 3.0)
  337.  
  338.  
  339.  
  340.  
  341.  
  342.         History
  343.  
  344. 1.2     -I forgot to add the ansi 'erase display' <csi>2J command so
  345.          screens where not cleared in ansi sequences.
  346.         -Ansi reversed video added
  347.         -The there will only be waited after a rip_no_more '|#' command
  348.             -when the screen must be cleared
  349.             -there is no text displayed after the rip_no_more command
  350.              (except for button text)
  351.             -The left mouse button isn't pressed after the rip_no_more command
  352.         -Palette can be changed. This can be turned on/off in the preferences
  353.          window.
  354.         -RIP_CIRCLE and RIP_ARC commands now use an aspect ratio of 13:10
  355.         -The circle commands didn't work when the begin angle was bigger than
  356.          the end angle.
  357.         -Changed the RIP_BEZIER a bit so a few rip sequences work better
  358.         -A user variable editor is added, RIP_DEFINE added
  359.         -All 'important' query commands added, CON, COFF, SBARON, SBAROFF, 
  360.          VT102ON, VT102OFF,  DWAYON, DWAYOFF, HKEYON, HKEYOFF, TABON,
  361.          TABOFF, APPx and sound Variables (except BEEP)  don't do anything.
  362.         -If the RIP_QUERY doesn't recognizes a query it will pop up a
  363.          requester  where you can enter the query or cancel the requester.
  364.         -Mode 1 and 2 of the RIP_QUERY command added so Variables can be sent
  365.          after the user has clicked the text of graphical window.
  366.         -You can enter the default main rip, icon and graphical font directory
  367.         -The preferences will be saved after closing the emulation window if
  368.          the terminal hasn't done this.
  369.         -Faster iconloading.
  370.         -The RIP_FILL command is now buffered so if there are some FILL
  371.          commands after each other the fill doesn't have to read the
  372.          windows rastport which takes a lot of time. This can make fills
  373.          twice as fast.
  374.         -The restore clipboard query didn't allocate memory correctly so the
  375.          computer could crash freeing the memory.
  376.         -Added a lowmemory handler. The icons are flushed out of the memory
  377.          when other programs can't get enough memory or after you typed 
  378.          'avail flush' in the cli. This works from kick 3.0.
  379.         -Stored the icon not found picture in the library. Now the icon
  380.          is always shown if the library can't find an icon.
  381.          
  382.  
  383. 1.1        16-Sep-94
  384.  
  385.         -Some small bugs fixed
  386.         -You can now use the library in border windows
  387.         -No more reading directly from bitmaps. Sometimes if there was
  388.          a window in front is the terminalwindow and you closed
  389.          that window the window was still displayed in the terminal
  390.          window. Because the data isn't red directly from the bitmap
  391.          the fill routine is slower.
  392.         -You can now use the library with more terminal program's at once
  393.         -Now the library waits when necessary after a '|#' command. In the
  394.          previous version the library waited never normally. But when
  395.          replaying a capture it waited always.
  396.  
  397. 1.0        -First release programmed in 19 days                27-Aug-94
  398.  
  399.  
  400.  
  401.  
  402.         Bug reports
  403.  
  404. If you find a bug, have some ideas for the xemrip.library, you can email me at:
  405. srave@sterbbs.nl or write me a letter. My address is:
  406.  
  407.  
  408.         Stef Rave
  409.         Dorpstraat 69
  410.         7361 AS Beekbergen
  411.         Holland
  412.  
  413.  
  414.  
  415.  
  416.         Copyright & legal stuff
  417.  
  418. xemrip.library is freeware (You may copy and use it for free)
  419.  
  420. The program and files in this distribution are freely distributable, but are
  421. also copyright (c) Stef Rave. They may be freely distributed as long as no more
  422. than a nominal fee is charged to cover time and copying costs.
  423.  Everything in this distribution must be kept together, in original unmodified
  424. form.
  425.  
  426. No guarantee of any kind is given that the program described in this document
  427. is 100% reliable. You are using this material on your own risk.
  428.  
  429.  
  430.  
  431.  Installer and Installer project icon
  432.  (c) Copyright 1991-93 Commodore-Amiga, Inc. All Rights Reserved.
  433.  Reproduced and distributed under license from Commodore.
  434.  
  435.  INSTALLER SOFTWARE IS PROVIDED "AS-IS" AND SUBJECT TO CHANGE;
  436.  NO WARRANTIES ARE MADE. ALL USE IS AT YOUR OWN RISK. NO LIABILITY
  437.  OR RESPONSIBILITY IS ASSUMED.
  438.